Lucas A. Meyer
2022-07-07
Content stuck in my computer is nearly worthless.
Donald E. Knuth proposed literate programming in a 1984 article.
One of my proudest tech moments was to make CWeave and CWeb (and LaTeX) run in a Windows computer circa 1998.
Jupyter implements the literate programming paradigm, but I haven’t seen the Markdown part gain a lot of traction.
\usepackage{ifthen}@for, @whileblogdown work wellRAbout 75% of data scientists use Python through Jupyter notebooks, and one can use pandoc to generate papers and PowerPoint, but it can be complicated.
graph LR
A[.ipynb] --> B(("Pandoc"))
B ----> E[.doc]
B ----> H[.pptx]
B --> C[.md]
B --> D[.tex]
D --> F((Xetex))
C --> I((Hugo))
F --> G[.pdf]
I --> J[.html]
style B fill:#FF6655AA
style F fill:#88ffFF
style I fill:#88ffFF
In Quarto’s .qmd files, you write Markdown and code, just like .ipynb. Add some YAML configuration and Quarto does the intermediate steps. It integrates well with VSCode and Jupyter.
graph LR
Q[.qmd] --> A
subgraph Quarto
A[.ipynb] --> B(("Pandoc"))
B --> C[.md]
B --> D[.tex]
D --> F((Xetex))
C --> I((Hugo))
style B fill:#FF6655AA
style F fill:#88ffFF
style I fill:#88ffFF
end
B ----> E[.doc]
B ----> H[.pptx]
F --> G[.pdf]
I --> J[.html]
Quarto can easily run pre-scripts and post-scripts. I frequenly use this to pre-process data and to automatically publish output to git repositories.
graph LR
P[Pre-scripts] --> Q
style P fill:#AA99FF
Q[.qmd] --> A
subgraph Quarto
A[.ipynb] --> B(("Pandoc"))
B --> C[.md]
B --> D[.tex]
D --> F((Xetex))
C --> I((Hugo))
style B fill:#FF6655AA
style F fill:#88ffFF
style I fill:#88ffFF
end
B ----> E[.doc]
B ----> H[.pptx]
F --> G[.pdf]
I --> J[.html]
E --> X[Post-scripts]
H --> X
G --> X
J --> X
style X fill:#AA99FF
Whether you use Quarto from .qmd, .ipynb, or .Rmd files, you always start with a YAML front-matter file.
The YAML configuration determines what’s the output format of your document. A few popular output options are html, pptx, docx, and pdf.
You can use a single source file to generate multiple output types.
For example, the YAML on the right will generate a PowerPoint file and a Revealjs presentation.
Most writing in Quarto is done in Markdown.
Quarto’s Markdown supports everything I’m used to: figures, tables, bibliography, etc.
It also supports lots of extra features, like diagrams with mermaid and GraphViz and even LaTeX equations:
\[ E = mc^2 \]
The best thing about Quarto is that you can use it to run any code that you would be able to run in a Python notebook.
To create slides, you create sections with #, titles with ##, and bullets with -.
To generate a presentation from a .qmd file, add format: pptx to the YAML front-matter.
The part I liked the least is that Quarto will use the pandoc PowerPoint rules to render the content from the .qmd into the .pptx.
The “pandoc rules” substantially limit the flexibility you would have in PowerPoint presentations. Quarto has better presentation support for revealjs and beamer.
The rules are available at:
https://pandoc.org/MANUAL.html#powerpoint-layout-choice
title and author#).md source contains .columns div (:::: {.columns}) and text contentcolumns div but has text and non-text contentBy adding a reference-doc entry to your YAML, you can tell Quarto (and pandoc) to use a file as a template for the format of your presentation.
The “Slide Master” needs to contain layouts named as per the previous slide (e.g. “Comparison”).
This allows you a lot of flexibility in the design of your slide deck, even if it is for just the small number of layouts that were listed in the previous slide.
You can control fonts, add background images, page numbering, etc.
Let’s say you’re presenting a project about population dynamics but you don’t know which world leaders are coming to the conference.
On the presentation day, you learn that Belgium, China, Brazil, India, Japan and Nigeria are attending.
You can use Python or R to automatically generate slides.
The next slides/sections were generated using the code below:
df_dr = pd.read_csv("data/dr.csv.gz", compression="gzip")
df_pop = pd.read_csv("data/pop_brackets.csv.gz", compression="gzip")
years = [2000, 2025, 2050, 2075, 2100]
regions = ["Belgium", "China", "Brazil", "India", "Japan", "Nigeria"]
for name in regions:
display(Markdown(f"## Age and Population Pyramids for {name}"))
display(Markdown(f'<div class="columns">'))
display(Markdown(f'<div class="column">'))
plot_dependency_ratio(df_dr[df_dr.Location == name])
display(Markdown(f'</div>'))
display(Markdown(f'<div class="column">'))
plot_population_pyramid_series(df_pop[df_pop["Location"]==name], years)
display(Markdown(f'</div>'))
display(Markdown(f'</div>'))
---
title: "Using Quarto for everything"
format: html
# revealjs:
# incremental: false
# theme: [simple, revealjs-customizations.scss]
# title-slide-attributes:
# data-background-image: images/data-viz-bg.jpg
# data-background-size: contain
# data-background-position: right
author: Lucas A. Meyer
date: 2022-07-14
---Adding or changing the format to html will create a website.
I reused some of the content of this presentation to create two scholarly-looking articles. The purpose of the articles is just to show how easy it is to generate them with Quarto, they don’t contain original research.
The relevant files are:
It’s very easy to use citations in Quarto. All you need is a BibTex file with your citations, for example, bibliography.bib, and to add bibliography: references.bib to the YAML front-matter of your document. You can then refer to the bibliography by simply adding the appropriate [@citation-name] in your text. For example, if my BibTex file contains a diamond97 and a diamond11 citation for Jared Diamond’s books, I can cite them by writing [@diamond97] and [@diamond11]. I can then cite _Guns, Germs and Steel [@diamon97] and Collapse [@diamond11]. All Citation Style Language formats are supported.
Generating footnotes is also easy, using [^ref] links to a footnote, and [^ref: content of the footnote] generates its content1.
I have been using Quarto a lot lately. Here’s my current (July 2022) take on when it’s worthwile.
I wanted to have a Python-based blog for a long time, and Quarto delivers it well. Now I can automate my blog to tweet and post to LinkedIn when I write new articles.
If I would be doing something in a Python notebook, I don’t lose anything by doing it on Quarto, and the extra work is very small.
I think Quarto is more helpful for a team that uses Git with Python notebooks or LaTeX to write articles. Microsoft Word collaboration through SharePoint and Teams is easier than Git and Quarto… but it’s not reproducible.
The best case for generating a presentation with Quarto are when you need to generate a lot of dynamic content. Other cases:
